package org.queueify.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * The Retry annotation allows retry parameters to be set for a {@link QueueifyTask} object. This is a thin layer to the
 * underlying appengine queue retry-parameters, documented here: 
 * http://code.google.com/appengine/docs/java/config/queue.html#retry_parameters
 * 
 * <p>
 * Configures retry attempts for failed tasks. This addition allows you to specify the maximum number of times to retry failed
 * tasks in a specific queue. You can also set a time limit for retry attempts and control the interval between attempts.
 * </p>
 * 
 * <ul>
 * <li>taskRetryLimit: The maximum number of retry attempts for a failed task. If specified with task-age-limit, App Engine retries
 * the task until both limits are reached.</li>
 * <li>minBackoffSeconds: (push queues only) The minimum number of seconds to wait before retrying a task after it fails.</li>
 * <li>maxBackoffSeconds: (push queues only) The maximum number of seconds to wait before retrying a task after it fails.</li>
 * <li>maxDoublings: (push queues only) The maximum number of times that the interval between failed task retries will be doubled
 * before the increase becomes constant. The constant is: 2**(maxDoublings - 1) * minBackoffSeconds.</li>
 * <li>taskAgeLimitSeconds: (push queues only) The time limit for retrying a failed task, in seconds, measured from the time the task
 * was created. The value is a number followed by a unit of time, where the unit is s for seconds, m for minutes, h for hours,
 * or d for days. For example, the value 5d specifies a limit of five days after the task's first execution attempt. If specified
 * with taskRetryLimit, App Engine retries the task until both limits are reached.</li>
 * </ul>
 * 
 * @author broc.seib@gmail.com
 *
 */
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Retry {
	/**
	 * minBackoffSeconds: (push queues only) The minimum number of seconds to wait before retrying a task after it fails.
	 */
	double minBackoffSeconds() default -1.0d;
	
	/**
	 * maxBackoffSeconds: (push queues only) The maximum number of seconds to wait before retrying a task after it fails.
	 */
	double maxBackoffSeconds() default -1.0d;
	
	/**
	 * maxDoublings: (push queues only) The maximum number of times that the interval between failed task retries will be doubled
	 * before the increase becomes constant. The constant is: 2**(maxDoublings - 1) * minBackoffSeconds.
	 */
	int maxDoublings() default -1;
	
	/**
	 * taskAgeLimitSeconds: (push queues only) The time limit for retrying a failed task, in seconds, measured from the time the task
	 * was created. The value is a number followed by a unit of time, where the unit is s for seconds, m for minutes, h for hours,
	 * or d for days. For example, the value 5d specifies a limit of five days after the task's first execution attempt. If specified
	 * with taskRetryLimit, App Engine retries the task until both limits are reached.
	 */
	long taskAgeLimitSeconds() default -1;
	
	/**
	 * taskRetryLimit: The maximum number of retry attempts for a failed task. If specified with task-age-limit, App Engine retries
	 * the task until both limits are reached.
	 */
	int taskRetryLimit() default -1;
	
}
